Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: conform docstrings to PEP257 #365

Merged
merged 19 commits into from
May 20, 2024
Merged

docs: conform docstrings to PEP257 #365

merged 19 commits into from
May 20, 2024

Conversation

tseaver
Copy link
Member

@tseaver tseaver commented May 18, 2024

See: https://peps.python.org/pep-0257/#multi-line-docstrings

Break argument descriptions into separate chunks, and make them more direct.

Also, remove a Python2 compatibility fossil.

See: https://peps.python.org/pep-0257/#multi-line-docstrings

Break argument descriptions into separate chunks, and make them more
direct.

Also, remove a Python2 compatibility fossil.
Copy link
Member

@stevepiercy stevepiercy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs build fails on RTD because it lacks a .readthedocs.yaml. See https://readthedocs.org/projects/colander/builds/24402967/

Copy link
Member

@stevepiercy stevepiercy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixes a few typos and reST and English syntax.

I noticed there is inconsistency between the use of **strong** and *emphasis*. In pylons-sphinx-themes, text with a bold font style is indistinguishable from normal text, due to the chosen font family. I recommend using *emphasis* instead.

From Pyramid docs, this snippet:

https://github.com/Pylons/pyramid/blob/72f61853beda8e21b669c3520e43fe3e5b224ba3/docs/quick_tutorial/requirements.rst?plain=1#L30-L33

* **Workspaces, projects, and packages.** Our home directory will contain a
  *tutorial workspace* with our Python virtual environment and *Python
  projects* (a directory with packaging information and *Python packages* of
  working code.)

Renders as:

Screenshot 2024-05-18 at 1 09 53 PM

https://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/requirements.html

Note that strong (bold) face renders slightly blurry for normal text, whereas emphasis renders clearly in italic.

Also, now that I've finally figured out how to design Sphinx themes, I created a theme for Plone that could be adapted for Pylons Projects.

src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
src/colander/__init__.py Outdated Show resolved Hide resolved
tseaver and others added 17 commits May 19, 2024 14:20
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>
@tseaver tseaver force-pushed the tseaver-docstring-cleanup branch from afd5d0d to 3a35224 Compare May 19, 2024 21:09
@tseaver tseaver merged commit 7ccca7b into main May 20, 2024
31 checks passed
@tseaver tseaver deleted the tseaver-docstring-cleanup branch May 20, 2024 00:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants